feat: add HowTo JSON-LD schema to quickstart guides#1165
Open
kevlil83 wants to merge 5 commits into
Open
Conversation
Adds a reusable JsonLd snippet and HowTo structured data to 39 quickstart index pages across native, SPA, webapp, and backend platforms. Improves discoverability in AI search (ChatGPT, Perplexity, Google AI Overviews) and in traditional search rich results by exposing each quickstart's steps as machine-readable HowToStep entries. Also corrects four pre-existing broken links surfaced by Lychee in the Next Steps sections of files being touched: - golang: Production Checklist -> Production Readiness Checks (/deploy-monitor/pre-deployment-checks/production-checks-best-practices) - express: Add Authorization -> /manage-users/access-control/rbac - express: Call Protected APIs -> /secure/tokens/access-tokens/get-access-tokens - java: drop Support Center link (auth-gated 302); keep Community
4 tasks
Summary
Redirects per inputRedirects in main/docs/quickstart/backend/aspnet-core-webapi/index.mdx
Redirects in main/docs/quickstart/backend/fastapi/index.mdx
Redirects in main/docs/quickstart/backend/golang/index.mdx
Redirects in main/docs/quickstart/backend/python/index.mdx
Redirects in main/docs/quickstart/native/android-facebook-login/index.mdx
Redirects in main/docs/quickstart/native/android/index.mdx
Redirects in main/docs/quickstart/native/ionic-angular/index.mdx
Redirects in main/docs/quickstart/native/ionic-react/index.mdx
Redirects in main/docs/quickstart/native/ionic-vue/index.mdx
Redirects in main/docs/quickstart/native/ios-swift-facebook-login/index.mdx
Redirects in main/docs/quickstart/native/maui/index.mdx
Redirects in main/docs/quickstart/native/react-native-expo/index.mdx
Redirects in main/docs/quickstart/native/wpf-winforms/index.mdx
Redirects in main/docs/quickstart/spa/flutter/index.mdx
Redirects in main/docs/quickstart/spa/react/index.mdx
Redirects in main/docs/quickstart/webapp/aspnet-core-blazor-server/index.mdx
Redirects in main/docs/quickstart/webapp/aspnet-core/index.mdx
Redirects in main/docs/quickstart/webapp/express/index.mdx
Redirects in main/docs/quickstart/webapp/fastapi/index.mdx
Redirects in main/docs/quickstart/webapp/fastify/index.mdx
Redirects in main/docs/quickstart/webapp/nextjs/index.mdx
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
mikemimik
requested changes
May 13, 2026
Contributor
mikemimik
left a comment
mikemimik
left a comment
There was a problem hiding this comment.
❓ Question: @kevlil83 where on the page is this script tag supposed to be for AI agents to find it?
ℹ️ When this renders the
scripttag is deep in the structure of the page, as denoted by the image below
❓ Question: @kevlil83 the description mentions that this fixes broken pages, which implies this wasn't broken at one time. Do you have reference examples of what these pages looked like when they weren't broken to help compare to?
| export const JsonLd = ({ data }) => ( | ||
| <script | ||
| type="application/ld+json" | ||
| dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} |
Contributor
There was a problem hiding this comment.
dangerouslySetInnerHTML to add this text to the script tag. There is a way to do this using react refs that can do the same thing without using the dangerouslySetInnerHTML tag.
import { useEffect, useRef } from 'react';
export const JsonLd = ({ data }) => {
const scriptRef = useRef(null);
useEffect(() => {
if (scriptRef.current) {
// Safely stringify and set as raw text
// INFO: this example does a string replace to denote
// that you can do that here.
const safeJson = JSON.stringify(data).replace(/</g, '\\u003c');
scriptRef.current.text = safeJson;
}
}, [data]);
return <script type="application/ld+json" ref={scriptRef} />;
};
Contributor
Author
There was a problem hiding this comment.
❓ Question: @kevlil83 the description mentions that this fixes broken pages, which implies this wasn't broken at one time. Do you have reference examples of what these pages looked like when they weren't broken to help compare to?
@mikemimik thanks for the review here. Not sure I'm following this comment. A few quickstarts had 404's in the next steps section linking to pages that didn't exist anymore. Lychee caught these and I just fixed them as part of this PR.
Contributor
Author
There was a problem hiding this comment.
@mikemimik for the script comment, swapped dangerouslySetInnerHTML for the ref + useEffect pattern with the escape and pushed that up. On the placement question, would be ideal but Mintlify doesn't give us a way to inject custom script tags there. No docs.json or frontmatter option for it today. The JSON-LD spec allows the tag in either or , and crawlers scan the full DOM, so it still gets picked up where it is. At least thats my understanding from my research 🤷♂️
agiannelli-auth0
previously approved these changes
May 13, 2026
Replaces dangerouslySetInnerHTML with the useRef + useEffect pattern suggested in code review, including a < -> < escape to guard against the JSON ever containing content that could break out of the script tag. Behavior on Mintlify is equivalent.
hazel-nut
requested changes
May 14, 2026
Contributor
hazel-nut
left a comment
hazel-nut
left a comment
There was a problem hiding this comment.
i'm not in love with this implementation requiring us to manually duplicate all the step information.
given that the quickstarts already use the Steps component, a better approach may be to extract it from there.
Per review discussion, strips per-page HowTo step/tool data from the JSON-LD schema across all 39 quickstarts. The page-specific fields were maintained by hand and duplicated info already present in the rendered Steps component. With only @context and @type left, all pages emit the same payload, so the data lives inside the JsonLd component and pages just render <JsonLd />. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
kevlil83
force-pushed
the
feat/quickstart-jsonld-schema
branch
from
573efef to
13ca1b3
Compare
The snippet only ever emits a HowTo schema, but the generic JsonLd name implied broader scope. Renaming to HowToSchema makes the intent obvious and leaves room for sibling components (e.g. ArticleSchema) when other schema types are needed, rather than turning one component into a type-switch. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
kevlil83
commented
May 18, 2026
Contributor
Author
kevlil83
left a comment
kevlil83
left a comment
There was a problem hiding this comment.
@mikemimik quick update on this thread. After Hazels review I stripped all the per-page step/tool data from the schema and moved the @context and @type into the snippet itself. Also renamed the snippet to HowToSchema since thats all it emits. Pages just render now.
kevlil83
commented
May 18, 2026
Contributor
Author
kevlil83
left a comment
kevlil83
left a comment
There was a problem hiding this comment.
@hazel-nut per our slack thread I went the simpler route and stripped the per-page step data from the schema. Snippet now just emits @context and @type, and lives in the component itself so theres no duplication. Also renamed it to HowToSchema while I was in there. Mind taking another look?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
main/snippets/JsonLd.jsx— a minimal reusable snippet that renders a<script type="application/ld+json">tag from a data prop.HowTostructured data to 39 quickstartindex.mdxpages across native, SPA, webapp, and backend platforms, exposing each guide's steps as machine-readableHowToStepentries.Why
Experiment for project HockeyStick. Improves discoverability in AI-powered search (ChatGPT, Perplexity, Google AI Overviews, Gemini) and in traditional search rich results. Quickstarts are our highest-intent entry pages — making their step structure machine-readable helps these surfaces cite and summarize them accurately.
Scope
main/snippets/JsonLd.jsx(6 lines)/ui) rebuild needed —JsonLdis an MDX snippet, not a componentLink fixes included
backend/golang/deploy-monitor/production-checks(404)/deploy-monitor/pre-deployment-checks/production-checks-best-practiceswebapp/express/quickstart/webapp/express/02-user-profile(404)/manage-users/access-control/rbacwebapp/express/quickstart/webapp/express/03-authorization(404)/secure/tokens/access-tokens/get-access-tokenswebapp/javahttps://support.auth0.com/(auth-gated 302)Test plan
cd main && mint devrenders without new errorsapplication/ld+jsonblock with valid JSON is present/docs/quickstart/webapp/nextjs,/docs/quickstart/backend/golang,/docs/quickstart/spa/react,/docs/quickstart/native/ios-swiftSupersedes #1164 (closed with identical content; squashed to a single commit).